home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 551-575 / disk_572 / wbstart / wbstart.doc < prev    next >
Text File  |  1992-05-06  |  4KB  |  109 lines
  1. Documentation for WBStart V1.0                                       24.11.1991
  2.  
  3. This program is freely distributable, but copyrighted by me. This means that
  4. you can copy it freely as long as you don't ask for any more money than a
  5. nominal fee for copying. THIS APPLIES TO GERMAN PD DEALERS TOO!!! This program
  6. may be put on PD disks, especially on Fred Fish's AmigaLibDisks. If you want to
  7. distribute this program you MUST keep this document and the source code with
  8. it. Program, document and source code must be distributed in their original
  9. unmodified form. Of course you can use an archiver like LHarc to make it
  10. available on mailboxes and FTP sites. This program cannot be used for
  11. commercial purposes without written permission from the author. The author can
  12. not be made responsible for any damage which is caused by using this program.
  13.  
  14. Send comments, suggestions or bug reports to:
  15.  
  16.    Snail : Stefan Becker, Holsteinstrasse 9, 5100 Aachen, GERMANY
  17.    Domain: stefanb@cip-s01.informatik.rwth-aachen.de
  18.    FIDO  : 2:242/7.6, Stefan_Becker@mowgli.fido.de
  19.  
  20.  
  21.    I. What does it do?
  22.  
  23. WBStart is a package to emulate the Workbench startup procedure. Emulating this
  24. method is easy, because you only have to load a program, create a process for
  25. it and then send a WB startup message to it. But this startup message is a
  26. problem, because it contains memory and directory locks owned by your process
  27. and it is only returned after the WB process ends. So you can't leave your
  28. program until ALL WB processes you created have ended, or the replied messages
  29. will go into nowhere land.
  30.  
  31. WBStart solves this problem by using a handler process, which does the starting
  32. of the processes for you and then waits for the reply messages. You just send a
  33. message to the handler port, containing all needed information like name and
  34. parameters. The handler duplicates this information (so you can free your copy
  35. without worry and leave your program) and then starts the process.
  36.  
  37.  
  38.   II. Installation & Usage
  39.  
  40. Just copy the file WBStart-Handler into your L: directory. Be sure to set the
  41. execute flag on this file with
  42.  
  43.    Protect L:WBStart-Handler +e
  44.  
  45. You can break WBStart-Handler by sending a CTRL-C to its process. If all WB
  46. processes have returned, it will exit then.
  47.  
  48. WBStarter is an example program how to use the handler. It has the following
  49. syntax:
  50.  
  51.    WBStarter <command> [<command> ...]
  52.  
  53. WBStarter tries to start every command as WB process without parameters. The
  54. file names must contain absolute paths, or the handler won't be able to find
  55. the executables. If the handler is not running, WBStarter tries to start it.
  56.  
  57.  
  58.  III. How to use WBStart-Handler in your program
  59.  
  60. The handler opens a public message port named "WBStart-Handler Port". You must
  61. send a message of the following type to this port:
  62.  
  63.    struct WBStartMsg {
  64.                       struct Message  wbsm_Msg;
  65.                       char           *wbsm_Name;
  66.                       BPTR            wbsm_DirLock;
  67.                       ULONG           wbsm_Stack;
  68.                       LONG            wbsm_Prio;
  69.                       ULONG           wbsm_NumArgs;
  70.                       struct WBArg   *wbsm_ArgList;
  71.                      };
  72.  
  73.  wbsm_Msg
  74.   Standard message structure. You MUST initialize the mn_ReplyPort field to
  75.   your own message port.
  76.  
  77.  wbsm_Name
  78.   Pointer to a string, which contains the name of the program. The handler
  79.   recognizes project icons and extracts the default tool.
  80.  
  81.  wbsm_DirLock
  82.   Lock on a directory. wbsm_Name will be used relative to this directory.
  83.  
  84.  wbsm_Stack
  85.   Stack size for the new process. Minimum is 4096 Bytes. If a tool icon exists,
  86.   then the stack size from the icon is used. When this message is replied, this
  87.   field contains a boolean, which indicates the success of the action.
  88.  
  89.  wbsm_Prio
  90.   Priority of the new process. Must be in the range -128..127.
  91.  
  92.  wbsm_NumArgs
  93.   Number of arguments in wbsm_ArgList. May be 0.
  94.  
  95.  wbsm_ArgList
  96.   Pointer to an array of WB Arguments. These arguments contain lock on a
  97.   directory  and a pointer to a file name, which is relative to the directory.
  98.   Look into <workbench/startup.h> for the definition of this data structure.
  99.  
  100. Look into the C source for WBStarter to find out the details.
  101.  
  102.  
  103.   IV. Compilation
  104.  
  105. This program was compiled with DICE, Matt Dillon's superb C compiler. Just
  106. say "DMake" and it will produce the binary.
  107.  
  108.       Stefan Becker
  109.